setProp

Type

control structure

Summary

Handles the trigger sent to an object when you change one of its custom properties.

Syntax

setProp <propertyName> <newValue>
   <statementList>
end <propertyName>

Description

Use the setProp control structure to check the range of a custom property that is being set, or to change other properties or do other tasks at the same time a custom property is set.

Form: The first line of a setProp handler consists of the word "setProp" followed by the name of the custom property.

The last line of a setProp handler consists of the word "end" followed by the property's name.

A setProp handler can contain any set of LiveCode statements.

The propertyName is the name of the custom property whose value is being changed with the set command.

note

You cannot use a setProp handler to intercept a built-in property. The setProp control structure can be used only for custom properties.

The setProp trigger passes through the message path, the same as any other message, so a setProp handler for an object can be located in the object's script or in the script of any object further in the message path. For example, a setProp handler for a card property may be located in the script of the stack that the card belongs to.

If you use the set command within a setProp control structure to set the same custom property for the current object, no setProp trigger is sent to the object. (This is to avoid runaway recursion, where the setProp handler triggers itself.)

This is only the case for the custom property that the current setProp handler applies to. Setting a different custom property sends a setProp trigger. So does setting the handler's custom property for an object other than the one whose script contains the setProp handler.

warning

If a setProp handler in one object's script sets the custom property for a different object, and the first object is in the second object's message path, a runaway recursion will result. For example, if the following handler is in a card script, and you set the "myCustomProperty" of a button on the card, runaway recursion will result:

    setProp myCustomProperty pValue
        set the myCustomProperty of the target to pValue + 1
        -- Because the target is the button, and this handler is in
        -- the card, the above statement sends another setProp trigger
        -- to the button.
    end myCustomProperty

To avoid this problem, set the lockMessages property to true before setting the custom property.

You can include as many setProp handlers in a script as you need. The property that a setProp handler controls is determined by the propertyName parameter in the first line of the handler. (If a script contains two setProp handlers for the same property, the first one is used.)

If the custom property you want to control is in a custom property set, use array notation in the first line of the setProp handler, as in the following example:

    setProp mySet[pProperty] pValue
        if pProperty is \"that\" then put pValue into me
    end setProp

The above setProp handler responds to changes in the custom property named "that", which is a member of the custom property set named "mySet".

Important

You must either include the pass control structure or set the property explicitly in a setProp handler, if you want LiveCode to set the custom property. Otherwise, the setProp handler traps the call to set the property, and its value is not changed.

Parameters

Name	Type	Description
newValue	string
statementList		The statementList consists of one or more LiveCode statements, and can also include if, switch, try, or repeat control structures.
propertyName	string	A string up to 65,535 characters in length.

Related

object: stack, button

property: properties, customPropertySets, customProperties

command: call, set

control structure: pass, exit, setProp

function: propertyNames, paramCount, value

glossary: object, statement, handler, property, recursion, command, LiveCode, control structure, custom property set, trigger, custom property, handle, message path, trap, message, parameter, script

keyword: card, dollar

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile